Skip to main content
POST

​
Overview

Use this endpoint to kick off automated dialing for a batch once all data checks pass. The call processing runs asynchronously—responses confirm that the batch moved to the queue while individual call events continue to arrive through webhooks and batch polling.

​
Prerequisites

  • Batch already exists and contains the final contact list.
  • The authenticated user has Calling Management permissions.
  • Plivo webhooks are configured if you need real-time updates.

​
Request

​
string
required
Bearer token for an approved workspace administrator.
​
string
required
Identifier of the batch to start dialing.
​
string
required
ID of the user who owns the batch.
​
array[string]
Phone IDs the dialer should rotate through. Optional if batch already has calling numbers configured.
​
array[object]
Call records to process. Optional if batch already contains calls. If provided, these calls will be processed instead of existing batch calls.
​
string
Optional UUID for tracking this calling session.

​
Response

​
boolean
required
Indicates whether the batch was successfully queued for dialing.
​
integer
required
HTTP status code (200 for success).
​
object
Additional information about the started batch.

​
Error Handling

  • 400 Bad Request – Missing required parameters (batchId or userId).
  • 401 Unauthorized – Bearer token missing or expired.
  • 404 Not Found – Batch not found or user not found.
  • 500 Internal Server Error – Failed to start calling service; retry or contact support.
Calling Behavior:
  • If callData is provided, those calls will be processed (useful for immediate calling)
  • If callData is not provided, the system uses existing calls in the batch
  • The calling service runs asynchronously
  • Calls are queued and processed based on batch configuration (calling hours, allowed days, etc.)
  • Monitor progress using GET /api/call/batch-details/{batchId} or webhook callbacks

Authorizations

​
Authorization
string
header
required

Bearer token authentication for workspace access

Body

application/json
​
batchId
string
required
Example:

"6806382f98da85ec32fac955"

​
userId
string
required
Example:

"64e5f12345abcdef12345678"

​
callingNumbers
string[]
Example:
​
callData
object[]
​
uuid
string
Example:

"some-unique-uuid"

Response

Calling service started successfully